Chapitre 12 [dev] Mettre en place un projet de développement avec RStudio et GitLab

La mise en place du projet sur GitLab relève des [ChfDev]. Il s’agit de préparer les différents outils et options qui vont être utilisées lors du développement et de l’édition. Nous utilisons GitLab :

  • Comme serveur distant pour conserver l’historique des commits git
  • Comme lieu de discussion autour des besoins (issues)
  • Comme Kanban pour suivre l’avancée de la résolution des besoins (issues)
  • Comme lieu de stockage des comptes-rendus de réunions (wiki)

12.1 En résumé : Checklist 1ère issue GitLab

  • Définir sur quelle instance GitLab (e.g. https://gitlab.com) et dans quel groupe de projets vous allez travailler.

  • Créer un nouveau projet GitLab.

  • Ouvrir un premier ticket (issue) sur GitLab avec la liste à cocher suivante: Issues > New issue

    • S’assurer d’avoir réalisé toutes ces opérations avant de passer à la suite. Les explications de toutes ces opérations sont décrites ci-dessous.
- [ ] Créer les labels pour les _issues_ s'il n'y a pas déjà des labels globaux pour votre groupe.
    + Bloqué, Prêt, En cours, Révision, A valider
- [ ] Préparer le _Board_ pour les _issues_ : Issues > Board > Add List
    + Si les labels sont en double, allez dans : Issues > Labels. Supprimer tous les _"projects labels"_ en cliquant sur le bouton avec 3 points verticaux, puis _"Delete"_. La liste des labels est maintenant vide, mais si vous retournez dans le _Board_, vous aurez toujours les labels globaux disponibles, en un seul exemplaire.
    + Ajouter au board, dans l'ordre : Bloqué, Prêt, En cours, Révision, A valider. Les autres sont en bonus.
- [ ] Gérer la liste des utilisateurs et de leurs permissions
- [ ] Initier le projet R avec RStudio et tous les fichiers de doc nécessaires
- [ ] Créer une branche "production"
- [ ] Conserver "master" comme branche principale : Settings > Repository > Default Branch > "master" > Save
- [ ] Définir la stratégie pour les _merge request_ : Settings > general > Merge requests > (*) [Votre choix] > Save
- [ ] Créer une issue 'bloquée' pour les nouveaux arrivant avec le contenu nécessaire

12.2 Mise en place d’un projet sur GitLab

Créer un compte sur votre instance GitLab (e.g. https://gitlab.com).

  • Créer un nouveau projet : New Project

  • Choisir le groupe dans lequel le créer

  • Lui donner un nom approprié qui respecte les règles de nommage d’un package R.

    • Ne commence pas par un chiffre

    • Ne contient pas de caractères spéciaux autres que . , par exemple propre.rpls.

    • Ne contient que des minuscules

    • N’est pas un nom de package R déjà utilisé. Vous pouvez le vérifier dans R avec le package {available} : available::available("propre.rpls")

  • Ne pas cocher “Initialize repository with a README”

  • Choisir si votre projet est public ou privé (i.e. visible par n’importe qui sur Internet ou seulement par les membres du projet)

  • Valider la création du projet

  • Créer un premier ticket / issue

    • Issues > New issue

    • Y coller le contenu de la liste à cocher présentée dans le résumé ci-dessus

    • Soumettre l’issue

12.3 Gestion des issues avec le Kanban

Le développement est réalisé sur la base de tickets (issues) de demandes de fonctionnalités. Ces tickets seront priorisés, assignés et suivis grâce au Kanban de GitLab. L’utilisation du Kanban est rappelée dans les différentes parties de ce livre numérique selon les rôles de chacun.

Pour les [ChfDev], il s’agit de mettre en place le Kanban

  • Créer le “Board” (Kanban) : Issues > Boards

  • Ajouter les labels : Add List

    • N’ajouter les labels dans l’ordre suivant que s’ils existent et sont en un unique exemplaire: Bloqué, Prêt, En cours, Révision, A valider. Les autres sont en bonus.

  • Si les labels n’existent pas, les créer : Issues > Labels > New label

    • Bloqué (gris) : En attente d’infos complémentaires par les éditos [Ed]

      • labels supplémentaires si besoin (bug, feature, priorité 1, …)

    • En attente (vert pâle) {pas de colonne} : Issue non bloquante, en attente d’être prête, mais, n’étant pas une priorité pour le moment

    • Prêt (vert vif) : Le cahier des charges est clair, on sait ce qu’il faut faire, on est prêt à la prendre en charge

    • En cours (bleu) : Quelqu’un traite l’issue

    • Révision (orange) : L’issue est en merge request vers master

    • A valider (violet) : Attente validation par les éditos [Ed] pour passage en production

  • Vous pouvez définir des labels pour gérer les priorités. Vous devrez cocher l’étoile dans le menu des labels. Les tickets avec ce label seront affichés en premier dans les listes de tickets du Kanban

  • Si les labels sont en doubles, c’est qu’il y a des labels définis au niveau de vos groupes GitLab.

    • Allez dans : Issues > Labels.

    • Supprimer tous les “projects labels” en cliquant sur le bouton avec 3 points verticaux, puis “Delete”.

    • La liste des labels est maintenant vide, mais si vous retournez dans le Board, vous aurez toujours les labels globaux disponibles, en un seul exemplaire.

12.4 Gérer les utilisateurs et les droits

Dans la partie “Members” vous retrouverez la liste des utilisateurs ayant un accès à votre projet.

  • Si votre projet est public

    • Le monde entier peut voir le code, les issues, les wikis

    • Vous pouvez gérer une partie de ces permissions : Settings > General > Visibility, project features, permissions

    • Dans {propre.rpls}, nous avons décidé que le Wiki ne serait accessible qu’aux membres du projet car nous y partageons les comptes-rendus de réunion qui n’ont pas un intérêt particulier à être rendus accessibles.

  • Gérer les permissions des membres (les permissions listées ci-dessous s’ajoutent lorsqu’on descend dans la liste) :

    • Guest (public) : Peut voir le code, créer une issue, cloner le projet, créer un fork

    • Reporter : Peut assigner des [Dev] à des issues, gérer les labels, créer une merge request

    • Developer : Peut créer de nouvelles branches, gérer/accepter des merge requests, éditer le wiki, gérer des tags sur les commits

    • Maintainer : Peut ajouter des membres, protéger des branches, éditer les infos de projet, gérer l’intégration continue (CI), les Gitlab Pages, supprimer des pages du Wiki

    • Owner : Peut transférer, renommer le projet, rendre le projet privé, supprimer des issues, séparer un fork

12.5 Initier le projet R avec RStudio

12.5.1 Créer un projet de package R

Que le projet concerne un package R, une analyse de données, la création d’un rapport statique au format HTML et/ou PDF, nous utilisons toujours le format package R pour le développement. Si le projet concerne la création d’une application {shiny}, nous utilisons le format {golem} pour le développement. Notez qu’un golem est aussi un package R, avec des outils spécifiques à {shiny}.

  • Créer un nouveau projet RStudio en choisissant “New Directory”

    • Choisissez “R package using devtools” pour un package classique ou “Package for Shiny using golem” pour une application {shiny}

RStudio s’ouvre alors sur un nouveau projet avec un nouveau dossier contenant notamment l’arborescence suivante :

    <img src="images/paste-38581171.png" width="95%" style="display: block; margin: auto;" />
  • .Rbuildignore permet de lister les fichiers/dossiers qui ne doivent pas être pris en compte par le package, c’est le cas du fichier en .Rproj par exemple, qui indique qu’il s’agit d’un projet RStudio.
  • DESCRIPTION permet de décrire le contenu du package.
  • NAMESPACE sert à définir comment notre package interagit avec le monde extérieur (Liste des fonctions et dépendances à importer pour que notre package fonctionne et les fonctions exportées par notre package). Il ne doit pas être rempli à la main.
  • R/ est le dossier qui va contenir les fonctions de notre package.
  • .gitignore n’est pas forcément présent à cette étape. Il permet d’indiquer les fichiers/dossiers que l’on ne souhaite pas versionner sur git.

Notez que si vous aviez commencé un projet en local sans structure de package, il est toujours possible de rattraper le projet en suivant l’article “Quand le développement commence par la documentation” sur rtask.thinkr.fr

Le package {fusen} permet de créer un package à partir d’un ou plusieurs RMarkdown. Les développeurs débutants, mais aussi les aguerris peuvent avoir envie de se focaliser sur le contenu de la future publication, plutôt que sur la façon de ranger les différents fichiers dans un package R. Plus d’informations dans l’article : “{fusen}: Créer un package à partir d’un simple fichier RMarkdown”

12.5.2 Documenter le développement avec dev_history.R

Il est recommandé de lister toutes les opérations réalisées pendant le développement dans un script R nommé dev_history.R. Il contiendra ainsi tous les appels à {devtools}, {usethis}, {attachment}, … que nous allons faire et qui pourront vous servir de nouveau dans vos projets suivants.

  • Créer un nouveau dossier “dev/”
  • Créer un nouveau “R script” nommé dev_history.R et sauvez-le dans le dossier “dev/”. Attention à bien le sauver à la racine du projet, par défaut RStudio vous proposera le dossier R/, ce qu’il ne faut pas faire. Notez que dans le cas de {golem} ce genre de script se trouve déjà dans le dossier nommé dev/ .
  • Y écrire et exécuter usethis::use_build_ignore("dev/") pour cacher ce dossier lors de la création du package R.

En bref, un fichier dev/dev_history.R de démarrage peut ressembler à celui-ci. Les étapes sont détaillées dans les chapitres ou paragraphes suivants.

# Ignorer le dossier dev/ dans Rbuildignore car il ne doit pas être pris en
# compte dans la création du package
usethis::use_build_ignore("dev/")

# License du package
usethis::use_mit_license("ThinkR")

# Activer git et relier avec le serveur distant
usethis::use_git()
usethis::use_git_remote(url = "https://gitlab.com/<OWNER>/<REPO>.git")

# Activer {renv}
renv::activate()

# Documentation générale sur le package: README
usethis::use_readme_rmd()

# Lister les modifications et changements majeurs du package: NEWS
usethis::use_news_md()

# Créer le dossier de tests unitaires
usethis::use_testthat()

# Activer le CI
# Avec {usethis} ou une version plus avancée avec {gitlabr} (cf. issue #21)
usethis::use_gitlab_ci()
# gitlabr::use_gitlab_ci()

# Outils pour aider à gérer les dépendances pendant le développement de package
# A lancer régulièrement
attachment::att_amend_desc()

# A lancer après chaque git pull, fetch ou rebase
renv::restore()
# A lancer avant chaque git push
# _renv
custom_packages <- c(attachment::att_from_description(),
                     "renv",
                     "devtools", "roxygen2", "usethis",
                     "testthat", "covr", "attachment",
                     "pkgdown", "styler", "checkhelper")
# Tester le package
devtools::check()
# Store list of packages
renv::snapshot(packages = custom_packages)

# Tester le package de temps en temps
devtools::check()

12.5.3 Documenter les métadonnées du package avec le fichier DESCRIPTION

Le fichier DESCRIPTION contient les métadonnées du package R que vous allez créer. Vous devez y renseigner son objectif, sa description, ses auteurs et les dépendances permettant de l’utiliser. Une partie se fait manuellement, l’autre automatiquement en utilisant les bons outils.

  • Title : Un titre pour le package écrit au format titre (Majuscule à chaque mot, sauf mots de liaison)

  • Description : Une phrase qui se termine par un point.

  • Auteurs : Utiliser la ligne de commande suivante dans dev_history.R . Notez qu’il ne peut y avoir qu’un seul rôle de type mainteneur (i.e. Createur : "cre" ).

    desc::desc_add_author(given = "Sébastien", family = "Rochette", email = "sebastien@thinkr.fr", role = c("cre", "aut"),
  comment = list(ORCID = "xxxx-xxxx-xxxx-xxxx"), normalize = FALSE)

  • License : S’agissant de la licence d’utilisation, son choix est indispensable pour prévenir les utilisateurs de ce qu’ils peuvent faire ou non avec le code source.

    • Par défaut, du code sans licence n’est pas réutilisable.
    • Se référer au livre numérique sur les licences et R de Colin Fay, ThinkR. Dans tous les cas, vous pouvez utiliser une des fonctions de {usethis} du type : usethis::use_*_license("ThinkR") (à noter dans le dev_history.R).
    • Dans le cadre d’un projet ProPRe produit par la sphère statistique publique, les données sont a priori à licencier sous licence Etalab v2 (LO/OL) et il faut mentionner que la charte graphique “marque Etat” est d’un usage réservé aux services de l’Etat.

12.5.4 S’occuper du versionnement avec git

  • Activer git : usethis::use_git()

    • À noter dans le dev_history.R

    • Vous pouvez ou non choisir de créer un premier commit

  • Trouver l’url du projet sur GitLab en cliquant sur le bouton : Clone

  • Relier votre git local au serveur distant

    use_git_remote(url = "https://gitlab.com/<OWNER>/<REPO>.git")

  • Gérer les caractères de fin de ligne dans le projet avec “.gitattributes” (cf. §12.5.4.1)

  • Vous pouvez effectuer un premier commit

12.5.4.1 Gérer les caractères de fin de ligne

https://help.github.com/en/articles/dealing-with-line-endings

Le développement sur différents OS nécessite de gérer les caractères de fin de ligne, différents entre Windows, GNU Linux et MacOS

  • Fixer les caractères de fin de ligne à “POSIX (LF)” par défaut dans Rstudio dans les options globales (menu Tools / Global Options / Code / Saving / Serialization)
  • Définissez le nouveau caractère de fin de ligne par défaut de vos prochains projets git
    • Sur Windows, les caractères sont convertis au style Unix
    git config --global core.autocrlf true
    • Sur Linux ou MacOS, les caractères sont vérifiés comme étant correct pour Linux / OS X
    git config --global core.autocrlf input
  • Créer un fichier nommé .gitattributes avec le contenu suivant. Il doit être commit avec les autres fichiers
# Set the default behavior, in case people don't have core.autocrlf set.
* text=auto

# Declare files that will always have CRLF line endings on checkout.
*.Rd text eol=lf
*.R text eol=lf
*.Rmd text eol=lf
*.md text eol=lf
NAMESPACE text eol=lf
DESCRIPTION text eol=lf

# Denote all files that are truly binary and should not be modified.
*.png binary
*.jpg binary

S’il y a des caractères de fin de lignes différents, il ne seront modifiés par git qu’au moment d’ajouter les fichiers avec git add files, ou “staged” avec l’interface RStudio.

  • Si vous avez déjà commencé le développement entre différents OS ou que vous avez commencé sur Windows, il faut remettre tous les fichiers avec le même caractère de fin de ligne pour repartir sur de bonnes bases.
    • Assurez-vous d’avoir défini le nouveau caractère de fin de ligne par défaut de tous vos prochains projets git
      • Sur Windows, les caractères sont convertis au style Unix
      git config --global core.autocrlf true
      • Sur Linux ou MacOS, les caractères sont vérifiés comme étant correct pour Linux / OS X
      git config --global core.autocrlf input
    • Sauver les fichiers en cours dans un commit pour éviter de perdre votre travail
      $ git add .
  $ git commit -m "Saving files before refreshing line endings"
    • Ajouter tous les fichiers modifiés et normaliser les caractères de fin de ligne. Ne pas se préoccuper du message de warning s’il y en a un.
      $ git add . --renormalize
    • Afficher la liste des fichiers ré-écrits et normalisés.
      $ git status
    • Commit les changements sur le serveur
      $ git commit -m "Normalize all the line endings"

12.5.5 Définir un environnement de travail figé avec {renv}

Le package {renv} permet de figer les versions de packages R utilisées lors du développement en ajoutant un fichier de configuration au projet. Ainsi pas de surprises de fonctionnalités manquantes ou obsolètes. Après réception des mises à jour du projet, chacun pourra ainsi s’assurer d’utiliser le même environnement que les autres développeurs. Vous pouvez mettre en place {renv} dès maintenant pour partir sur de bonnes bases.

  • Une condition au bon fonctionnement de {renv} est que tout le monde utilise la même version de R, tant qu’à faire, la plus récente. Définissez la version sur laquelle travailler et assurez-vous que tous les développeurs utilisent la même. La variable R.version, à taper directement dans la console, vous donne les informations nécéssaires. Le cas échéant, les développeurs seront notifiés par {renv} qu’ils ont une version de R non conforme.

  • Vous avez peut-être besoin d’installer {renv}

remotes::install_github('rstudio/renv')
  • Activer {renv}
renv::consent(provided = TRUE) # Vérifier la console
renv::activate()

  • Relancer la session RStudio

  • Définir le dépôt CRAN à utiliser

    • Avec https://packagemanager.rstudio.com/, vous pouvez choisir une date figée dans le temps. Aucune version de package arrivée après cette date ne pourra être installée dans le projet
    • L’url ci-dessous ne fige pas de date et prend la dernière version disponible le jour du téléchargement d’un package
options(repos = c(REPO_NAME = "https://packagemanager.rstudio.com/all/latest"))
  • Créer un snapshot des packages nécessaires au projet actuel
    • Cela fige aussi la version R et le repos en cours d’utilisation
renv::snapshot()
  • Vous pouvez vérifier le contenu de renv.lock. Celui-ci sera envoyé dans le dépôt git, ainsi que le fichier ".Rprofile" modifié par {renv}, pour être pris en compte par toutes celles et ceux qui vont charger le projet.

Notez que pour travailler dans des conditions encore plus reproductibles, vous pouvez aussi tous travailler dans le même conteneur Docker qui figerait à la fois la version de R, les packages, mais aussi l’architecture système. Ce conteneur pouvant être utilisé pour une mise en production à l’issue du développement pour éviter les surprises. Le package {devindocker} peut faciliter ce mode de fonctionnement. Référez-vous à l’article : “Comment développer dans un conteneur Docker pour faciliter la collaboration ?”

12.5.6 Documenter le dépôt git avec un README

  • Créer le fichier README de documentation générale : usethis::use_readme_rmd()

    • Pour le remplir, vous pouvez vous aider de {chameleon} : chameleon::create_pkg_desc_file(to = "markdown")
    • Ne pas oublier de le knit avant d’envoyer sur le serveur git distant

  • Ce fichier doit au minimum :

    • informer de ce que fait votre package. A priori les mêmes informations que la description de votre fichier DESCRIPTION .

    • présenter comment un utilisateur peut installer le package sur son propre ordinateur.

    • présenter l’utilisation de base avec un exemple reproductible. Cet exemple sera alimenté en cours de développement.

  • Le fichier est créé au format .Rmd ce qui permet d’exécuter du code R à l’intérieur. Ne pas oublier de le knit avant d’envoyer vos modifications sur le serveur distant.

12.5.7 Documenter les modifications du projet avec les NEWS

  • Créer le fichier qui listera les modifications notables de chaque version de votre projet : usethis::use_news_md()

  • Ce fichier stockera, pour chaque nouvelle version, les changements dans l’utilisation du package, les nouveautés apportées, les modifications pouvant casser les flux de travail, …

  • Vous pouvez commit à nouveau

12.5.8 Initialiser les tests unitaires

  • Créer le dossier de tests unitaires : usethis::use_testthat()

12.5.9 Initialiser l’intégration continue

  • Créer le fichier de configuration pour l’intégration continue “.gitlab-ci.yml” de telle sorte que :
  • votre package soit testé à chaque commit
  • le pourcentage de couverture de code soit calculé à chaque commit
  • le site de documentation {pkgdown} soit créé pour la branche master et la branche production indépendamment
  • Créer une version de base avec usethis::use_gitlab_ci() ou une version plus avancée avec {gitlabr} (cf. issue #21)
  • Vérifier que ce fichier est caché de l’étape de construction du package (build) avec usethis::use_build_ignore(".gitlab-ci.yml")

12.5.10 Dernières vérifications avant premier envoi sur le serveur

  • Lancer la première documentation et gestion des dépendances : attachment::att_amend_desc()

  • Lancer la première vérification de conformité : devtools::check()

    • On vise 0 errors, 0 warnings, 0 notes

  • Commit et push sur le serveur pour tester toute votre configuration

  • Vérifier sur GitLab que le README est correctement affiché et que le CI est correctement passé

12.6 Gestion des branches du git : GitLab-flow et branches-issues

La gestion des branches de git se fait en suivant un format de type GitLab-flow :

  • master : La branche “master” est la branche principale de développement, celle vers laquelle toutes les branches vont converger. Note: vous pouvez nommer cette branche “main”.

  • production : La branche “production” ne doit contenir que les versions “fiables” du projet. Celles que l’on livre, qui sont mises en production et a priori taguées. Les [ChfDev] mettent en place cette branche au lancement du projet depuis GitLab :

    • Repository > Branches > New branch : “production”
    • Create from master

  • branches-issues : Les développeurs créent des nouvelles branches à partir de “master”
    • Le nom de la branche contient le numéro de l’issue (ticket/cas/question) à régler
    • Rapatrier les modifications critiques depuis “master” vers les branches avec un cherry-pick si nécessaire (si la MR indique qu’il y a des conflits par exemple), puis seulement, demander la fusion vers “master”.
    • Plus courtes seront les modifications de branches, plus facile sera la fusion dans le “master”
    • Privilégier de nombreuses “branches-issues” avec des petites issues à traiter, quitte à les subdiviser.

12.6.1 Présentation d’un GitLab Flow complet

Branche master et branches-issues

Figure 12.1: Branche master et branches-issues

Branche de production

Figure 12.2: Branche de production

12.6.2 Définir le niveau de protection des branches

La protection des branches selon les niveaux d’habilitation des participants permet d’éviter quelques erreurs.

  • Settings > Repository > Protected Branches
  • Protéger les branches master et production
  • Choisir les rôles qui peuvent “merge” ou “push”
    • “Maintainers” pour tout
    • Éventuellement pour master : “Allowed to Merge” > “Maintainers + Developers”, mais pas pour “Push”.
    • Vous pouvez empêcher de “push” sur master et production car nus sommes censés faire des “Merge Requests” pour ajouter nos modifications
      • “Allowed to push” : “No one”

En tant que mainteneurs, vous aurez peut-être parfois besoin de “push” directement sur le master lorsque vous faites des “Merge Requests” en local pour gérer des conflits. Dans ce cas, revenez sur cette page pour autoriser temporairement l’envoi

12.7 Choisir un mode pour les Merge Requests

Nous aurons un chapitre dédié à l’utilisation de git par les développeurs “Collaboration sur un projet Git”, mais nous pouvons déjà définir un schéma pour accepter les Merge Requests. Dans les options de projet GitLab, il est possible de forcer une méthode de fusion de branches : Settings > general > Merge requests > (*) [Votre choix] > Save

  • Le mode recommandé est le merge commit qui fusionne deux branches avec un commit de merge. git décide par lui-même de conserver la dernière version du code s’il y a eu des modifications dans le même fichier sur deux branches différentes. Un commit est ajouté automatiquement pour signaler la fusion et permet de garder une vraie trace de l’historique du développement. Cette méthode peut impliquer aux développeurs qui veulent se mettre à jour, de faire une fusion dans leur branche ou un chery-pick avant de pouvoir faire une demande de fusion vers la branche principale, ce qui peut conduire à des commits en double. Nous verrons dans la partie “Collaboration sur un projet Git” ce que cela implique

  • Le mode fast-forward merge, peut protéger de nombreux risques de pertes de code mais requière une bonne compréhension du fonctionnement de git et une bonne maîtrise de la ligne de commande. Il nécessite aussi une bonne communication entre les développeurs. Cela implique aux développeurs d’être toujours à jour des dernières modifications présentes sur la branche principale (dev ici) et de gérer eux-mêmes les éventuels conflits. Cela implique aussi aux [ChfDev] de savoir qui travaille sur quoi pour éviter au maximum les conflits, mais aussi d’être réactifs à l’arrivée des Merge Requests pour éviter que plusieurs arrivent en même temps.

  • Le mode merge commit with semi-linear history nécessite des branches en fast-forward mais ajoute quand même un commit de merge. C’est une combinaison des deux approches ci-dessus.

Il est nécessaire d’informer clairement l’équipe de développement de cette décision dans la plateforme de Chat et lors de la première réunion de l’équipe de développement car elle a un impact sur la façon de développer et d’utiliser git. Notez que vous pouvez changer de stratégie en cours de développement si vous informez clairement les participants.

Pour voir ce que cela implique concrètement pour les développeurs, vous pouvez aller à la section “Comment se maintenir à jour avec la branche master”

12.8 Choisir l’effet des Merge Requests sur les issues

Il est recommandé de ne pas laisser GitLab fermer automatiquement les issues au moment de la fusion vers master, comme c’est la coutume.
Dans un processus de développement PROPRE, ce sont les [Ed] qui valident la bonne prise en compte des fonctionnalités. Les [ChfDev] ne ferme les issues que lorsque les [Ed] les ont validées.

Pour cela, dans GitLab

  • Allez dans “Settings” > “Repository” > “Default Branch”
  • Décocher la case “Auto-close referenced issues on default branch” comme dans l’image ci-dessous

12.9 Documenter le dépôt GitLab pour les nouveaux utilisateurs

Les échanges entre les utilisateurs, le comité éditorial [Ed] et l’équipe de développement seront tous stockés dans les tickets GitLab.

  • Dans les tickets “bloqués”, les personnes mentionnées apporteront les informations nécessaires au déblocage du développement.
  • Les tickets en attente de validation seront commentés par les éditeurs pour validation
  • Inviter les utilisateurs dans le projet
  • Choisir le niveau de droit de chacun
    • En tant que “Guest” dans le dépôt créé pour le projet, ils pourront voir le Kanban, mais pas le code (sauf projet open-source).
  • Créer un Wiki avec les informations principales du projet
    • Le Wiki sert de table d’orientation. Dans le cas d’un projet open-source, la plupart des informations peuvent être mises dans le fichier README car il est accessible à tous. Ce n’est pas le cas d’un projet privé avec des “Guest”.
      • La première page du Wiki (Home) est utilisée pour lister les liens vers les autres pages.
      • Créez une page nommée “Comptes-rendus” pour stocker tous les comptes-rendus de réunions.
      • Créez une page nommée “Cahier des charges” pour stocker la trame de publication / cahier des charges ou définir une autre stratégie de collaboration.
      • Rappelez le lien vers les produits dérivés du développement (pkgdown, publication, application, …), la page des comptes-rendus, la page du cahier des charges.
      • Une proposition est la suivante (Remplir les {URL} et autre {mon.projet})
## Bienvenue

Vous êtes sur la page d'accueil du projet {mon.projet}  
A tout moment, vous pouvez y revenir en utilisant l'adresse du Wiki : https://{URL}/{mon.projet}/-/wikis

## Présentation de la production
https://{URL}

## Présentation de la documentation technique du package
https://{URL}/{projet-pkgdown}/

## Compte-rendus de réunions
https://{URL}/{mon.projet}/wikis/Comptes-rendus

## Cahier des charges / Trame de publication
https://{URL}/{mon.projet}/wikis/Cahier-des-charges

## Profil personnel
Vous pouvez changer vos préférences personnelles dans votre page de profil: https://{URL}/profile  
Notamment, vous pouvez passer l'interface en français.

## Tableau de bord

Le tableau de bord d'avancement des tickets du projet : https://{URL}/{mon.projet}/boards  

- Les tickets sur lesquels les développeurs sont bloqués sont listés dans la colonne `bloqué`. Merci de bien vouloir explorer ces tickets et répondre aux questions.
- Dès lors que vous répondez ou êtes nommés dans un ticket, vous recevrez un email en cas d'ajout d'une nouvelle réponse

Il est possible de n'afficher que la liste des tickets bloqués (ceux qui vous concernent) en cliquant sur ce lien suivant: {URL}

## Issues / Tickets

L'interface des issues présente le contenu de la demande puis la liste des questions et réponses. Elle contient aussi tout l'historique des modifications de status. Pour alléger la page, il est possible de n'afficher que les commentaires, pour cela, il faut cliquer sur le menu déroulant sous la présentation de l'issue. Et choisir l'option qui permet de n'afficher que les commentaires.

Vous pouvez vous désabonner des emails reçus dans une issue en modifiant le bouton bleu "Notifications" dans la colonne en bas à droite de l'interface. 

## Développement

- R 4.0.1
- Utilisation de {renv} pour figer les versions des packages utilisées
- Développement dans un Docker avec Ubuntu Focal Fossa et {devindocker}
  • Créer un ticket en mode bloqué avec le contenu suivant
    • Assigner le ticket aux chefs du comité éditorial
    • Titre : Bienvenue sur le suivi de projet GitLab
    • Dans le contenu ci-dessous, changer le mot {mon.projet} (3 fois) par le nom de votre projet sur GitLab pour l’url du Kanban.
    • Dans le contenu ci-dessous, sélectionnez le mode de partage des comptes-rendus et mettez à jour le lien.
    • Contenu :
Bonjour et bienvenue sur le Kanban de suivi de projet.  

_Si vous lisez ce message depuis vos emails, merci de cliquer sur le lien en bas "View it on GitLab" ou "Lire sur GitLab"._

Ce site web est l'outil de développement GitLab. Il permet aux développeurs de versionner leur code (conserver l'historique des modifications) et de communiquer sur les fonctionnalités en cours de développement. 

Le message que vous lisez actuellement est un ticket de suivi (aussi appelé "issue"). C'est sous ce format que nous listons toutes les fonctionnalités demandées et bugs divisés en unités de développement. C'est aussi sous ce format que la totalité de nos échanges devront être stockés. Nous évitons les Emails pour conserver l'historique des échanges, rangés dans les tickets dédiés, pour ne rien perdre des besoins et demandes.  

Au cours du développement, vous serez peut-être amenés à :  

- **répondre aux points de blocage**. Pour cela, comme pour le présent ticket, vous serez notifiés par un Email qui contient un lien pour venir sur l'interface. Pour répondre, vous pouvez écrire un message dans la partie dédiée ci-dessous, quand vous avez le temps de le faire. *Nous vous demandons d'ailleurs de bien vouloir écrire un message dès à présent et de le valider. Merci.*  
- **suivre l'avancement du projet** dans le Kanban dédié. Ce Kanban se trouve à l'adresse suivante que vous pouvez ouvrir dès à présent dans un nouvel onglet : <https://{URL}/{mon.projet}/-/boards>
    + Vous verrez que le ticket que vous êtes en train de lire se trouve dans la colonne *"Bloqué"*. Cette colonne de tickets vous est adressée. Tous les tickets qui s'y trouvent nécessitent des informations complémentaires pour être traités. En théorie, vous aurez reçu un email pour chacun d'entre eux, mais s'il y en a trop, vous savez maintenant où les retrouver.  
- **valider les tickets terminés**. Dans le Kanban, il y a une colonne en fin de Kanban nommée *A valider*. Il s'agit des tickets qui nécessitent une validation de la part du comité éditorial et/ou des utilisateurs.  
  + Lorsque c'est possible, les tickets peuvent être validés directement après lecture, sans nécessité de réunion en direct. Vous pourrez écrire un message du type : "Je valide la fermeture de ce ticket."
  + En cas de ticket plus complexe ou plus technique, il sera validé lors d'un point d'avancement en direct. Auquel cas, nous validerons la fermeture dans le compte-rendu de réunion.
  
Notez que nos échanges lors de réunions en direct seront rédigés et accessibles pour tous dans :
- [ ] Le Wiki de ce projet : <https://{URL}/{mon.projet}/-/wikis/home>

Merci de bien vouloir nous indiquer que vous avez lu et approuvé à la date d'aujourd'hui ce mode de fonctionnement en écrivant : "lu et approuvé, le {date du jour}" (Mettre la date du jour) dans un message ci-dessous (Emplacement "Write" ou "Ecrire") et valider l'envoi du message en cliquant sur le bouton vert "Comment" ou "Envoyer".  
Suite à quoi, les responsables du développement se chargeront de fermer ce ticket.
  • Ajouter un commentaire s’il y a plusieurs personnes à suivre le projet pour mentionner toutes les personnes nécessaires de façon à ce qu’elle reçoivent un mail de notification.

12.10 Définir le mode de participation de l’équipe éditoriale

L’équipe éditoriale [Ed] est là pour vous fournir tous les titres et textes nécessaires à la rédaction de votre publication. Ne vous inquiétez pas, ils sont au courant, on leur en parle dans “Rédiger et fournir les textes en RMarkdown”

Vous allez devoir choisir et mettre en place le moyen de récupérer ces textes sans faire trop de copier-coller depuis des fichiers au format peu utilisable, depuis lesquels il est difficile de savoir ce qui est nouveau ou non. Une discussion s’impose entre les [ChfDev] et les [Ed]. Autrement dit, pas de fichiers créés avec des logiciels de traitement de texte classiques.

Les [Ed] peuvent envisager une formation à git dédiée à l’écriture collaborative de textes en Markdown. Les interfaces de RStudio et GitLab/GitHub rendent ce genre d’outils accessibles à tous. Cela simplifiera les échanges [Dev]/[Ed].

Pour cela, vous avez trois stratégies possibles de la moins contraignante pour les [Ed], à la moins contraignante pour les [Dev]. Dans tous les cas, il sera demandé aux [Ed] de rédiger les différents textes au format Markdown. C’est la raison pour laquelle, on vous parle de Markdown dès le début dans “Utiliser le format Markdown pour prendre les notes”

  • Trame dans un sous-dossier du projet de développement, nommé "trame/" (Stratégie RMarkdown)
    • Penser à ignorer ce dossier pour la construction du package : usethis::use_build_ignore("trame/")
  • Trame dans un dépôt Git à part (Stratégie RMarkdown)
  • Trame dans le Wiki GitLab (Stratégie Markdown seulement)

La première stratégie, avec le dossier inclus dans le projet de développement, est recommandée car elle permet aux [ChfDev] de réviser les modifications au même endroit que le reste du développement. S’il y a des modifications apportées, elles sont directement visibles et peuvent donner lieu à la création ou la modification d’un ticket au même endroit.

Noter qu’il y a d’un côté la trame, qui recense les besoins des [Ed], qui permet de créer les tickets de développement, qui fait partie des dossiers de développement, mais qui ne fait pas partie du package R. Et de l’autre, le corps de la publication reproductible, qui est complété au fur et à mesures des développements, avec des blocs de code R, et qui fait partie intégrante du package R (dans "inst/" a priori). Le contenu de ces deux documents a bien entendu des points communs, en particulier le plan et les différents titres.